Programming With QuickTime Sprites
| Previous | Chapter Contents | Chapter Top |
This section describes functions that you use to create and manipulate sprites.
The NewSprite function creates a new sprite in the specified sprite world.
pascal OSErr NewSprite (Sprite *newSprite,
SpriteWorld itsSpriteWorld,
ImageDescriptionHandle idh,
Ptr imageDataPtr,
MatrixRecord *matrix,
Boolean visible,
short layer);
You call this function to create a new sprite associated with a sprite world. Once you have created the sprite, you can manipulate it using SetSpriteProperty .
The newSprite , itsSpriteWorld , visible , and layer parameters are required. Sprites with lower layer values appear in front of sprites with higher layer values. If you want to create a sprite that is drawn to the background graphics world, you should specify the constant kBackgroundSpriteLayerNum for the layer parameter.
You can defer assigning image data to the sprite by passing nil for both the idh and imageDataPtr parameters. If you choose to defer assigning image data, you must call SetSpriteProperty to assign the image description handle and image data to the sprite before the next call to SpriteWorldIdle . The caller owns the image description handle and the image data pointer; it is the caller's responsibility to dispose of them after it disposes of a sprite.
The DisposeSprite function disposes of a sprite.
pascal void DisposeSprite (Sprite theSprite);
The InvalidateSprite function invalidates the portion of a sprite's sprite world that is occupied by the sprite.
pascal void InvalidateSprite (Sprite theSprite);
In most cases, you do not need to call this function. When you call the SetSpriteProperty function to modify a sprite's properties, SetSpriteProperty takes care of invalidating the appropriate regions of the sprite world. However, you might call this function if you change a sprite's image data, but retain the same image data pointer.
The SpriteHitTest function determines whether a location in a sprite's display coordinate system intersects the sprite.
pascal OSErr SpriteHitTest (Sprite theSprite,
long flags,
Point loc,
Boolean *wasHit);
You call this function to determine whether a sprite exists at a specified location in the sprite's display coordinate system. This function is useful for hit testing a subset of the sprites in a sprite world and for detecting multiple hits for a single location.
You should apply the sprite world's matrix to the location before passing it to SpriteHitTest . To convert a location to local coordinates, you should use the GlobalToLocal function to convert the location to your window's local coordinate system and then apply the inverse of the sprite world's matrix to the location.
You use the spriteHitTestBounds and spriteHitTestImage flags in the flags parameter to control the hit test operation. Set the spriteHitTestBounds flag to check if there has been a hit anywhere within the sprite's bounding box. Set the spriteHitTestImage flag to check if there has been a hit anywhere within the sprite image.
The GetSpriteProperty function retrieves the value of the specified sprite property.
pascal OSErr GetSpriteProperty (Sprite theSprite,
long propertyType,
void *propertyValue);
You call this function to retrieve a value of a sprite property. You set the propertyType parameter to the property you want to retrieve. The following table lists the sprite properties and the data types of the corresponding property values.
In the case of the kSpritePropertyImageDescription and kSpritePropertyImageDataPtr properties, this function does not return a copy of the data; rather, the pointers returned are references to the sprite's data.
The SetSpriteProperty function sets the specified property of a sprite.
pascal OSErr SetSpriteProperty (Sprite theSprite,
long propertyType,
void *propertyValue);
You animate a sprite by modifying its properties. You call this function to modify a property of a sprite. This function invalidates the sprite's sprite world as needed.
You set the propertyType parameter to the property you want to modify. Depending on the property type, you set the propertyValue parameter to either a pointer to the property value or the property value itself, cast as a void* .
The following table lists the sprite properties and the data types of the corresponding property values.
| Previous | Chapter Contents | Chapter Top |